refactor(java)!: switch idioms, deprecations, Lombok, warning gate - #198

Summary

One idiom sweep over the api-sheriff corpus, bracketed between the two halves of the build
mechanism that keeps it from silently regressing: <showDeprecation> goes on first so the
compiler — not grep — enumerates the deprecation set, and <failOnWarning> goes on last, once
the corpus is clean.

This is a deliberate BREAKING change (compatibility: breaking). Per the repository's Pre-1.0
Rules there are no deprecation markers, no transitional shims and no backward-compatibility path:
AuthConfig.require changes type from String to a bound Require enum, the deprecated
quarkus.log.file.enable property is replaced outright by quarkus.log.file.enabled, and
failOnWarning now makes a compiler warning a build failure across all six reactor modules.
Anything downstream that constructs an AuthConfig with a string, sets the old property, or
compiles with a warning present will break — intentionally.

Changes

The bracket

• pom.xml — <showDeprecation>true</showDeprecation> added to the pluginManagement
maven-compiler-plugin entry (opens the bracket), then <failOnWarning>true</failOnWarning>
  (closes it). Reactor-wide, all six modules; javac now runs with -Werror.
• CLAUDE.md — the Pre-Commit Process prose reconciled with what the gate now actually
  enforces, so the mechanism and its description agree.

AuthConfig.require: String → Require enum

• New api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/model/Require.java; consumers
  moved in lockstep across AuthConfig.java, ConfigValidator.java, AuthenticationStage.java,
  GatewayEdgeRoute.java and RouteTableBuilder.java; the enum registered in
  ConfigModelReflection.java for the native image. Three duplicated REQUIRE_* constant sets
  retired. No YAML/doc value moves — ConfigLoader enables ACCEPT_CASE_INSENSITIVE_ENUMS, so
  none / bearer / session keep their lowercase spelling on the config surface.

Deprecated quarkus.log.file.enable migration

• Six carriers, 20 occurrences: api-sheriff/src/main/resources/application.properties,
  integration-tests/docker-compose.yml (7, env spelling),
  doc/development/README.adoc, .claude/skills/run-integration-tests/SKILL.md,
  ShippedApplicationPropertiesTest.java, ItProfileConfigBindingWiringTest.java.
• The replacement was researched against the shipped artifact before any carrier was edited:
  io.quarkus.runtime.logging.LogRuntimeConfig.FileConfig in quarkus-core-3.38.1 declares both
  the deprecated Optional<Boolean> enable() (@Deprecated(since = "3.26", forRemoval = true)) and
  the replacement boolean enabled() (@WithDefault(false)). Key → quarkus.log.file.enabled,
  env → QUARKUS_LOG_FILE_ENABLED. The shipped OFF-by-default posture (ADR-0032) is preserved
  and expressed more strongly: the replacement carries a framework-level false default where the
  deprecated accessor had none.

Java deprecation retirement (enumerated by the compiler, not by grep)

• Five sites in four files. The framework-boundary one is WebSocketRelayStage.java, migrated off
  the deprecated HttpClient WebSocket path onto the Vert.x WebSocketClient; the two
  HttpServerRequest.host() fallbacks in GatewayEdgeRoute.java are retired against
  authority().

Surveys (published enumeration is the deliverable)

• if/else-if → switch: 19 files surveyed, 3 chains converted in ConfigLoader.java and
  GatewayEdgeRoute.java. TokenValidatorProducer.applyJwks qualifies but sits outside the
  deliverable's declared footprint and was deliberately deferred rather than smuggled in.
• Lombok against the java-lombok decision table: 30 files surveyed, zero mutations. 23
  @Builder-on-record and 6 @UtilityClass sites match the table verbatim; RouteRuntime.java is
  kept as a @Builder @Getter final class because its four @Builder.Default fields cannot live on
  a record — a conversion would trade declarative fail-closed defaults for a hand-written partial
  builder.
• OpenRewrite unnamed-variable recipe: none exists in any module this build already resolves.
  Every OpenRewrite jar in the resolved repository was swept (UseUnnamed / UnnamedVariable /
  UnnamedPattern) with zero hits; the active UpgradeToJava25 recipe list
  (rewrite-migrate-java 3.40.0) and rewrite-static-analysis 2.39.0 declare none. No recipe was
  appended and pom.xml carries no change from this deliverable. Residual, deliberately left open:
  a module the build does not resolve might carry one — adding a module is a new dependency and
  out of scope.

Operator decisions (recorded verbatim, and load-bearing on this review)

Two questions were put to the operator during outline authoring. Both answers are reproduced here
because the authority behind them should be auditable rather than inferred.

q1 — the enum-conversion rationale. Asked because the outline's own first-party verification
had REFUTED both justifications the request gave for the conversion, leaving the change without the
rationale it was requested on.

Answer: "Proceed as outlined (type-safety only)"

The operator re-confirmed the full conversion after reading the refutation. Deliverable 4
therefore proceeds on a narrowed, type-safety-only rationale, and a reviewer should hold it to
exactly that and no more:

• What it does buy: compile-time typing of the auth posture, plus retirement of the three
  duplicated REQUIRE_* constant sets (AuthenticationStage, ConfigValidator,
  GatewayEdgeRoute).
• What it does NOT buy — do not approve it on these grounds: there is no behavioural delta
  and no security improvement. The claim that "nothing rejects an unknown require value today"
  is false: gateway.schema.json and endpoint.schema.json already declare
  "require": {"type": "string", "enum": ["none", "bearer", "session"]}, and ConfigLoader runs
  schema validation before bind, so require: bearerr is already refused at load time as a
  collected ConfigError. It never reaches AuthenticationStage. The startup-rejection behaviour
  this change was originally pitched on already existed.

q2 — the WebSocket client dependency. Asked because the epic carries a "never add dependencies
or plugins without explicit user approval" clause and the WebSocketRelayStage fix appeared to need
a new artifact.

Answer: "Use the new dependency, hereby accepted."

That is the explicit operator approval the clause requires — and the approval went unused. It
was treated as a permission, not an instruction: the outline first verified whether an artifact
was genuinely required, and it is not. io.vertx:vertx-core:4.5.30 is already on the api-sheriff
compile classpath and already contains io/vertx/core/http/WebSocketClient.class, with
Vertx.createWebSocketClient() declared on io.vertx.core.Vertx in the same jar.

No new Maven artifact is added by this PR. Recording the approval anyway matters: a reviewer
seeing "no dependency added" should be able to tell the difference between a constraint that
blocked a fix and a fix that turned out not to need the allowance it was granted. This is the
second.

Pre-submission self-review: two contract-drift defects caught and fixed

The self-review pass before submission found and fixed two defects, both landed in b94f17b. They
are named here rather than buried in the diff, because both are the kind a green suite does not
catch:

1. The Require dispatch was not compiler-checked for exhaustiveness. A constant-only switch
   statement is a legacy switch, so it carries no exhaustiveness requirement — a future fourth
   Require constant would have fallen through silently while the route still reported itself
   AUTHENTICATED. That is a fail-open auth path. Converted to a form the compiler must prove
   exhaustive.
2. The authorityHost Javadoc asserted a false equivalence between host() and
   authority().host(). The two are not interchangeable in the case the fallback exists to handle;
   the doc now describes what the code actually does.

Test Plan

• Quality gate green on the whole reactor at HEAD (verify -Ppre-commit)
• Full Maven verify green on the whole reactor at HEAD (verify)
• 1873 module tests green
• WebSocketProxyIT 8/8 green against a freshly built native image (111 integration tests
  total) — the WebSocket client swap is the only framework-boundary change here and the native
  image is where a Vert.x client swap historically surprises, so a JVM-only pass was not
  accepted as discharge
• Negative control on the new gate: with failOnWarning on, a deliberately re-introduced
  deprecated HttpServerRequest.host() call failed the build (status: error,
  exit_code: 1), with the offending site reported as GatewayEdgeRoute.java:1169. Worth
  recording precisely: the file and line land on the warnings[] row while errors[]
  carries the -Werror cause naming the file without a line — so the payload does carry
  file+line, just not both on one errors[N] row. Scratch edit reverted; the file's diff is
  empty. A gate that has never been observed to fail is not known to gate.

Related Issues

Refs #178 — the deprecated quarkus.log.file.enable migration (6 carriers / 20 occurrences) is the
work that issue asks for. It is deliberately not auto-closed by this PR: the issue gets a
comment naming this PR and the merge commit, and is closed post-merge.

Generated by plan-finalize skill

Intent

The problem. Compiler warnings were invisible to this project's agent-facing build surface. The
reactor configured maven-compiler-plugin with <release>25</release> only — no showDeprecation,
no -Xlint, no failOnWarning — so deprecated-API usage accumulated in the corpus unseen, and the
Maven executor's structured payload has no warnings channel to surface it through even when javac
does emit it. Alongside that, four idiom-level defects had accrued: a deprecated Quarkus logging
property, string-typed auth posture triplicated across three classes, if/else-if chains where a
switch belongs, and unaudited Lombok usage.

The approach. Bracket the corpus work between the two halves of the mechanism. showDeprecation
goes on FIRST, so the deprecation set is enumerated by running the compiler across the whole
reactor rather than by grepping for a guess — that is how five sites in four files were found where
the request had named two in one. failOnWarning goes on LAST, once the corpus is clean, because a
warning only reaches the executor's errors[] payload once it is a build failure; lint alone does
not make it visible to an agent. The order is load-bearing, not stylistic. Every deprecation site is
retired by migrating off the warned construct, never by suppressing it — a @SuppressWarnings
added to reach green would hollow out the gate while leaving it

[Intent truncated — 1393 of 2806 characters shown; full outline in the plan workspace]

Summary by CodeRabbit

• New Features

  • Authentication requirements now consistently support anonymous, bearer-token, and session access.
  • WebSocket relay connections are handled more efficiently.

• Bug Fixes

  • Corrected file-logging configuration properties and environment variables.
  • Improved handling of authentication configuration states.

• Documentation

  • Updated logging and integration-test guidance.
  • Expanded development guidance for compiler warnings and deprecations.